                                 Main commands
                               of DIO Interpreter

==================== Note =================================================

Abbreviations and conventions:

  * (val)  : Any type
  * (str)  : String
  * (num)  : Integer number
  * (real) : Real number
  * Integer numbers are 32 bit (including addresses)
  * Real numbers are 64 bit
  * Ret : Return value of a command

==================== Base =================================================

Exit: {\!}

Evaluation control: {%.|%+|%-|%!|%?}[{<num>}]
  .   : Modify control level
        <num> : Increment value (num); default:0
  +   : All commands are interpreted
        (evaluation enabled mode)
        <num> : Control level value (num); default:0
  -   : Only evaluation control commands are interpreted
        (evaluation disabled mode)
        <num> : Control level value (num); default:-1
  !   : Next command is always interpreted (in both mode)
  ?   : Get control mode (>=0:enabled,<0:disabled)
  Ret : {%?} : Control level

Insert string: {(?|.)[%]}{<str>}[{<par1>}...]
  ?      : Evaluate inserted string
  .      : Don't evaluate inserted string
  %      : Do not any parameter substitution
  <str>  : String to insert in (str)
  <parX> : Parameters (str)
  Parameter names within the value:
    {^N}      : The Nth parameter
    {^?}      : Number of parameters
    {^*[,|"]} : List of all parameters including the <nam>
    {^+[,|"]} : List of all parameters without the <nam>
    {^-[,|"]} : List of all parameters without the <nam> and
                the first parameter
    {^/}      : Enable parameter substiution (token will be deleted)
    {^\}      : Disable parameter substitution (token will be deleted)
  , : Enclose parameters with braces
  " : Enclose parameters with braces and with (")
  All double (^) character will be replaced to a single (^) character.
  All single (^) character will be ereased.

Insert character: {\}[{<char>}]
  <char> : Character number (num)
           (default:$)

Delete string: {_>}{<str>}
  <str> : String to delete (str)

Delete at position: {_:}{<pos>}{<len>}
  <pos> : Position (num)
  <len> : Length (num)

Conditional evaluation: {?=|?~}{<str1>}{<str2>}[{<true>}{<false>}[{_}]]
  The next block will be executed only if the condition is TRUE
  (if there are 3 parameters).
  =       : Equal
  ~       : Not equal
  <str1>  : 1. String (str)
  <str2>  : 2. String (str)
  <true>  : Result value if condition is true
  <false> : Result value if condition is false
  _       : Replace command with the result
  Ret     : The result value if the command has 5 parameters (str)

Skip block: {..}[{_}]
  Jump over the next block
  _ : Delete command

Evaluate in loop: {??}{<val>}{<str>}
  Evaluate command while <val> not 0 or NULL.
  <val> : Value to test
  <str> : String to evaluate

Find string: {?<|?>}{<str1>}[{<str2>}]
  <      : Find backward
  >      : Find forward
  <str1> : Head of string to find (str)
  <str2> : Tail of string to find (str)
  Ret    : Position (num)

Go to: {:}{<pos>}[{_}]
  <pos> : Position to go to (num)
  _     : Delete command

Call function: {@>}{<pos>}[{<par1>}...]
  <pos>  : Position of the function (num)
  <parX> : Parameters (val)
  Ret    : Function return value (val)
  Auto local values within the function:
    {^N} : The Nth parameter
    {^?} : Number of parameters

Call function with parameter array: {@:}{<pos>}{<pars>}
  <pos>  : Position of the function (num)
  <pars> : Name of parameter array (str)

Return from function: {@<}[{<val>}]
  <val> : Return value (val)

Append value to parameter array: {@+}{<nam>}{<val>}
  <nam> : Name of the parameter array (str)
  <val> : Value for append (val)

Append parameters to parameter array: {@+}{<nam>}{<pos>}{<cnt>}
  <nam> : Name of the parameter array (str)
  <pos> : The first parameter for append (num)
  <cnt> : Number of parameters (num)

Tools: {#|%|+}{<val1>}[{<val2>}...]
  #      : Length of the value
  %      : Last value
  +      : Concatenate values
  <valX> : Any values (val)
  Ret    : Listed above

Tools 2.: {+=}{<nam>}{<val1>}[{<val2>}...]
  +=     : Append to value
  <nam>  : Name (str)
  <valX> : Any values (val)
  Ret    : Listed above

Command buffer info: {&|^|#|=}
  &     : Buffer address
  ^     : Maximal buffer length
  #     : Current buffer length
  =     : Current buffer position
  Ret   : Listed above

Explicite return value: {##}{<adr>{<len>}
 <adr> : Address of the return value (num)
 <len> : Length of the return value (num)
 Ret   : Specified by the parameters

==================== Value ================================================

Add value: {<nam>}{:[~]}{<val>}[{<mLen>}[{<vLen>}]]
  ~      : Local value (with auto deletion)
  <nam>  : Name (str)
  <val>  : Value (val)
  <mLen> : Maximal value length (num)
  <vLen> : Current value length (num)

Delete value: {~}{<nam>}
  <nam>  : Name (str)

Get value: {*}{<nam>}
  <nam> : Name (str)
  Ret   : Value of name (val)

Get macro: {*?}{<nam>}
  <nam> : Name (str)
  Ret   : Value of name with parameter substitution (val)

Set value: {<nam>}{=}{<val>}
  <nam> : Name (str)
  <val> : New value (val)

Get/Set length: {<nam>}{#}[{<len>}]
  <nam> : Name (str)
  <len> : New length (num)
  Ret   : Old length (num)

Get max. length: {^}{<nam>}
  <nam> : Name (str)
  Ret   : Max. length (num)

Get/Set subvalue: {**}{<nam>}{<ofs>}{<idx>}{<len>}[{=}{<val>}]
  <nam> : Name (str)
  <ofs> : Offset (num)
  <idx> : Index (num)
  <len> : Item length (num)
  <val> : New subvalue (val)
  Ret   : Subvalue (val)

Load value DB: {%<}{<fnam>}
  <fnam> : Filename (str)

Save value DB: {%>}{<fnam>}[{'<'<from>}][{'>'<to>}]
  <fnam> : Filename (str)
  <from> : First value's name (nam)
  <to>   : Last value's name (nam)

==================== Conversion and I/O ===================================

Convert string to integer number: {#<}{<str>}
  <str> : String (str)
  Ret   : Number (num)

Convert integer number to string:
{#>}{<num>}[{[<|>][-|+][@][b|d|h|x]}[{<len1>}[{<len2>}]]]
  Format specifiers:
    < : Left aligned
    > : Right aligned
    - : Signed number
    + : Always show sign
    @ : Show number base prefix
    b : Binary base
    d : Decimal base
    h : Hexadecimal base
    x : Hexadecimal base
  <num>  : Number (num)
  <len1> : Number of digits (num)
  <len2> : String length (num)
  Ret    : String (str)

Convert string to real number: {.<}{<str>}
  <str> : String (str)
  Ret   : Number (real)

Convert real number to string:
{.>}{<num>}[{[.|E][<|>][+][!][;[' ']]}[{<len1>}[{<len2>}]]]
  Format specifiers:
    .   : Fixpoint number form
    E   : Normalized number form
    <   : Left aligned
    >   : Right aligned
    +   : Always show sign
    !   : All fraction digits
    ;   : Put digit group separators
    ' ' : Space is the digit group separator
  <num>  : Number (real)
  <len1> : Number of digits (num)
  <len2> : String length (num)
  Ret    : String (str)

Put string to the console: {<<}{<str>}
  <str> : String (str)

Get string from the console: {>>}{<nam>}
  <nam> : Name of the string (str)
  Ret   : String length (num)

==================== VP ===================================================

Call system function: {@@#}{<sys>}[{<par1>}...]
  <sys>  : System call number (num)
  <parX> : Parameters (num)
  Ret    : Return value of the system call (num)

Prepare VP to a function: {@@:}{<mem>}{<fn>}[{<par1>}...]
  <mem>  : Size of memory for VP (num)
  <fn>   : Name of function (str)
  <parX> : Parameters (num)

Call VP: {@@*|@@+}
  *   : Run
  +   : Step
  Ret : Run  : Return value of the called function, if
               it exit normally, otherwise -1 (num)
        Step : 1 if it hasn't exited otherwise 0 (num)

Get/Set VP state: {@@>|@@<}{<ps>}
  <ps> : Name of VP state (str)

Report VP state: {@@?}{<ps>}
  <ps> : Name of VP state (str)

Get DIO environment: {%%}{<env>}
  <env>  : Name of DIO environment (str)
  Environment format:
  * 0 : Processor type (num)
  * 1 : Operating system type (num)
  * 2 : DIO implementation type (num)
  * 3 : Pointer to the Evaluation descriptor

==================== Debug ================================================

Break current evaluation level and start a new:
{\+}{<fnam1>}{<fnam2>}{<val>}[{!}][{?}]
  !       : Trace the new input
  ?       : Save the returned buffer contents
  <fnam1> : Input filename (str)
            For console input: "."
  <fnam2> : Output filename (str)
            For console output: "."
  <val>   : Initial buffer contents

Restore the previous evaluation level: {\-}[{!}]
  !      : Trace the restored input

==================== Default ==============================================

{<nam>}[{<par1>}{<par2>}...]
* Works as "Insert string" but first it replaces the <nam> name
  with its value.
* The art of evaluation can be set explicitly (see eval.txt).
* The default value can be modifed by setting the value of <Val/Def>.
* You can also specify the name position (see eval.txt).

===========================================================================
